{
    "name": "It's a Trap!",
    "script": "ItsATrap.js",
    "version": "3.11",
    "previousversions": ["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "3.0", "3.1", "3.2", "3.3", "3.4", "3.5.2", "3.6", "3.7.4", "3.8", "3.9.1", "3.9.2", "3.9.3", "3.9.4", "3.10", "3.10.1"],
    "description": "# It's A Trap!\r\r_3.10 Updates:_\r\r* Shortened script menu macro's name.\r* Changed menu macro to NOT be a token action. (A lot of users seemed to be annoyed by this...)\r* Renamed, combined, and reordered some trap properties in the menu to _hopefully_ be more intuitive to users.\r\rThis is a script that allows GMs to quickly and very easily set up traps,\rsecret doors, and other hidden things on the GM layer, and detect when tokens\ron the objects layer move over them. This trap detection even works for tokens\rmoving by waypoints.\r\rCombined with modules called Trap Themes, this script also allows system-specific\rautomation of trap effects and passive perception used to spot them.\r\r## Trap Maker menu\rWhen this script is installed, it installs a macro called **TrapMaker**. When you\rselect a token that you want to set up as a trap and click this macro, it\rdisplays a **Trap Configuration** menu in the VTT's chat, from which you can\rmodify the trap's various properties (discussed below).\r\rWhen you use this menu on a token for the first time, it will be moved\rto the **GM layer** and it will be given the **cobweb** status marker. The script\ruses these properties to identify which tokens are active as traps.\r\rThe GM notes section of the trap's token will be used to hold the JSON data for\rthe trap's properties. Please do not edit the GM notes for a trap token\rmanually.\r\r### Enabling the menu macro\rThis macro is not added to your macro bar automatically, so you'll need to\rcheck the **In Bar** checkbox next to the **TrapMaker** macro to activate it.\r\r## Trap properties\rThe following subsections go into detail about each of the properties that can\rbe set and modified for a trap.\r\r### Core properties\rThese are the basic properties of the trap.\r\r#### Name\rThis is the name of the trap.\r\re.g. _'pit trap'_ or _'explosive runes'_\r\r#### Type\rThe It's A Trap! script, contrary to its name, can be used to automate more kinds of\rhidden objects than just traps. By default, the value of this property will just be\r_'trap'_, but you could define it to be something like _'hazard'_, _'hidden enemy'_,\ror _'concealed item'_ instead. This type will appear in the trap's header when\rit is activated.\r\rE.g., the header will read 'IT'S A TRAP!!!' if the type is 'trap', or\r'IT'S A HAZARD!!!' if the type is 'hazard'\r\rThis property otherwise has no mechanical effect.\r\r#### Message\rThis message will be displayed when the trap is activated.\r\re.g. _'You feel a floor sink under your feet as you step on a hidden pressure plate. Behind you, you hear the violent grinding of stone against stone, getting closer. A massive rolling boulder is heading this way!'_\r\r#### Disabled?\rThis sets whether the trap is currently disabled or not. A trap that is disabled\rcannot be triggered.\r\r#### Show GM Only\rThis sets whether the trap's activation will only be shared with the GM. If this\ris set to **yes**, the trap's GM Notes and its theme-based results will be\rshared only with the GM. Visible effects of a trap, such as the its message,\rsound, Areas of Effect, etc. will be ignored, and the trap will not be revealed.\r\rThis property is best used for traps, hazards, and alarms whose effects will\rnot be readily apparent when they are activated.\r\re.g. This could be set to 'yes' for a tripwire that alerts monsters in\ranother room to the party's presence.\r\r#### Secret Notes\rThese notes are whispered to the GM when the trap is activated. These notes won't be shown to any of the other players.\r\re.g. _'The tripwire sets off a silent alarm, alerting the mindflayers in the laboratory room to the party's presence.'_\r\r### Trigger properties\rThese properties all have to do with how the trap is triggered.\r\r#### Trigger Area\rThis defines the area that a character must move through in order to trigger the\rtrap. Options include:\r\r* **self - rectangle**: The trap's own token is used as the trigger area, which is treated as a rectangular shape.\r* **self - circle**: The trap's own token is used as the trigger area, which is treated as a circular shape.\r* **set selected lines**: You must have one or more lines selected on the VTT to use this option. Those lines will be used as the trigger area for the trap.\r\r#### Trigger Collision\rThis property defines how character tokens collide with the trap's trigger area. Options include:\r\r* **center**: When a character crosses the trap's trigger area, they are moved to the trap token's center. This option only works for traps whose trigger area is *self*.\r* **edge**: When a character crosses the trap's trigger area, their movement is stopped at the trigger area's edge.\r* **none**: Character tokens are not stopped when they move through the trap's trigger area.\r\rThis property is ignored if the Delay Activation property is set.\r\r#### Ignore Token IDs\rThis property is used to select one or more creature tokens that will not be affected by a trap. Neither can these tokens trigger the trap.\r\r* **none**: No ignored tokens.\r* **set selected tokens**: To use this option, you must have one or more tokens selected. These tokens will be ignored by the trap.\r\r#### Affects Flying Tokens\rBy default, traps will only affect tokens that are not flying. Tokens are treated as 'flying' by this script if they have the **fluffy wing** status marker active.\r\rIf this property is set to **yes**, it will affect all tokens, regardless of whether\ror not they have the **fluffy wing** status marker active.\r\rLeave this set to **no** for floor-based traps. For traps that affect creatures on\rthe ground and in the air alike, set this to **yes**.\r\r#### Delay Activation\rThis property sets a delay, in **seconds**, between when the trap is triggered to\rwhen it actually activates.\r\rAs a side-effect, the trap's trigger will be deactivated once this delay is\ractivated. This is to prevent the delayed trap from triggering multiple times.\r\r### Activation properties\rThese properties all have to do with what happens when the trap activates.\r\r#### Activation Area\rThis defines the area in which characters can be affected by the trap when it activates. Options include:\r\r* **self**: The trap's token is used as the activation area.\r* **burst**: The trap affects all characters within a certain radius of it.\r* **set selected shapes**: To use this option, you must have one or more filled shapes selected. The trap affects all characters inside those shapes.\r\r#### Burst Radius\rThis property is only visible if **Activation Area** is set to **burst**. This\rsets the radius of the burst area.\r\r#### API Command\rThis property can be used to issue an API chat command when the trap activates.\rThis property supports a couple keywords to support commands involving the trap\rand its victims.\r\rThe keyword TRAP_ID will be substituted for the ID of the trap's token.\r\rThe keyword VICTIM_ID will be substituted for the ID of token for some character\rbeing affected by the trap. If there are multiple victims affected by the trap,\rthe command will be issued individually for each victim.\r\re.g. _'!someApiCommand TRAP_ID VICTIM_ID'_\r\r#### Special FX\rThis property is used to display a particle effect when the trap activates,\rusing Roll20's special FX system.\r\rThe first prompt asks for the name of the effect that will be displayed. This can\reither be the name of a custom special effect you've created, or it can be the\rname of a built in effect. Built-in special effects follow the naming convention\r**effect-color**. e.g. _explode-fire_ or _beam-acid_\r\rSee https://wiki.roll20.net/Custom_FX#Built-in_Effects for more\rinformation on supported built-in effect and color names.\r\rThe second prompt allows you to specify an offset of the effect's origin point,\rin the format **[X,Y]**. The X,Y offset, relative to the trap's token is measured\rin squares. If this is omitted, the trap's token will be used as the effect's\rorigin point.\re.g. _[3,4]_\r\rThe third prompt allows you to specify a vector for the direction of the effect,\rin the format **[X,Y]**, with each vector component measured in squares. If this\ris omitted, the effect will be directed towards the victims' tokens.\re.g. _[0,-1]_\r\r#### Sound\rThis property sets a sound from your jukebox to be played when the trap is activated.\r\r#### Chained Trap IDs\rThis property allows you to set other traps to activate when this one does. Options include:\r\r* **none**: No other traps are activated by this trap.\r* **set selected traps**: You must have one or more other trap tokens selected to use this option. When this trap activates, the selected traps will activate too.\r\r#### Delete after Activation?\rIf this property is set to **yes**, then the trap's token will be deleted after it is activated.\r\r### Detection properties\r\r#### Max Search Distance\rThis property defines the distance at which a character can attempt to notice a\rtrap passively. If this is not set, the search distance is assumed to be infinite.\r\rDynamic lighting walls will block line of sight to a trap, even if the character\ris close enough to otherwise try to passively spot it.\r\re.g. If this is set to 10 ft, then a character must be within 10 ft of the trap in order to passively notice it.\r\r#### Reveal the Trap?\rThis property determines whether the trap's token will be revealed (moved to a visible layer) when it is activated and/or detected.\r\rThe first prompt asks if the trap should be revealed when it is activated (yes or no).\r\rThe second prompt asks if the trap should be revealed when it is detected (yes or no).\r\rThe third prompt asks which layer the trap token is moved to when it is detected (Just click OK or press enter if you chose **no** for both of the earlier prompts).\r\r### External script properties\rThese properties are available when you have certain other API scripts installed.\r\r#### Areas of Effect script\rThis property is only available if you have the **Areas of Effect** script installed.\rIt also requires you to have at least one effect saved in that script.\rThis allows you to have the trap spawn an area of effect graphic when it is triggered.\r\rThe first prompt will ask you to choose an area of effect chosen from\rthose saved in the Areas of Effect script.\r\rThe second prompt will ask for a vector in the form **[dx,dy]**, indicating the\rdirection of the effect. Each component of this vector is measured in squares.\rIf this vector is omitted, the effect will be directed towards the victims' tokens.\r\r#### KABOOM script\rThis property is only available if you have the **KABOOM** script\r(by Bodin Punyaprateep (PaprikaCC)) installed. This allows you to create a\rKABOOM effect centered on the trap's token. This can be handy for pushing tokens\rback due to an explosive trap!\r\rThe prompts for the property are used to define the properties for the KABOOM effect,\ras defined in the KABOOM script's documentation.\r\r#### TokenMod script\rThis property is only available if you have the **TokenMod** script (by The Aaron)\rinstalled. This allows you to set properties on tokens affected by the trap, using\rthe API command parameters described in the TokenMod script's documentation.\r\re.g. _'--set statusmarkers|broken-shield'_\r\r## Trap Themes:\rTrap themes are special side-scripts used to provide support for formatting messages for traps and\rautomating system-specific trap activation and passive search mechanics.\r\rBy default the **default** theme will be used. This is a very basic,\rsystem-agnostic theme and has no special properties.\r\rIf you install a system-specific trap theme, It's A Trap will automatically\rdetect and use that theme instead. Additional system-specific themes are\ravailable as their own API scripts.\r\r### Theme-specific properties\rTrap themes come with new properties that are added to the Trap Maker menu.\rThis includes things such as modifiers for the trap's attacks, the trap's\rdamage, and the dice rolls needed to passively detect the trap.\r\rDocumentation for these properties are provided in the script documentation for\rthe respective trap theme.\r\r## Activating traps:\rIf a character token moves across a trap's trigger area at ANY point during its\rmovement, the trap will be activated! Traps are only active while they are\ron the GM layer. Moving it to another layer will disable it.\r\rA trap can also be manually activated by clicking the 'Activate Trap' button\rin the trap's configuration menu.\r\r## Help\r\rMy scripts are provided 'as-is', without warranty of any kind, expressed or implied.\r\rThat said, if you experience any issues while using this script,\rneed help using it, or if you have a neat suggestion for a new feature,\rplease shoot me a PM:\rhttps://app.roll20.net/users/46544/stephen-l\r\rWhen messaging me about an issue, please be sure to include any error messages that\rappear in your API Console Log, any configurations you've got set up for the\rscript in the VTT, and any options you've got set up for the script on your\rgame's API Scripts page. The more information you provide me, the better the\rchances I'll be able to help.\r\r## Show Support\r\rIf you would like to show your appreciation and support for the work I do in writing,\rupdating, maintaining, and providing tech support my API scripts,\rplease consider buying one of my art packs from the Roll20 marketplace:\r\rhttps://marketplace.roll20.net/browse/search?category=itemtype:Art&author=Stephen%20Lindberg|Stephen%20L\r",
    "authors": "Stephen Lindberg",
    "roll20userid": 46544,
    "useroptions": [
        {
          "name": "announcer",
          "type": "text",
          "default": "Admiral Ackbar",
          "description": "What name is displayed in the chat for trap messages?"
        }
    ],
    "dependencies": [
      "Character Sheet Utils",
      "HTML Builder",
      "Token Collisions",
      "Path Math",
      "Vector Math"
    ],
    "modifies": {
        "chat": "write",
        "gmnotes": "read, write",
        "lastmove": "read, write",
        "layer": "read, write",
        "left": "read, write",
        "status_angel-outfit": "read",
        "status_bleeding-eye": "read",
        "status_cobweb": "read",
        "status_fluffy-wing": "read",
        "token": "read",
        "top": "read, write"
    },
    "conflicts": ["Blood and Honor"]
}